home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.3 / SetResult.3 < prev    next >
Text File  |  1995-07-25  |  13KB  |  199 lines
  1.  
  2.  
  3.  
  4.      TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt((((3333))))            TTTTccccllll ((((7777....0000))))            TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt((((3333))))
  5.  
  6.  
  7.  
  8.      _________________________________________________________________
  9.  
  10.      NNNNAAAAMMMMEEEE
  11.           Tcl_SetResult,     Tcl_AppendResult,      Tcl_AppendElement,
  12.           Tcl_ResetResult - manipulate Tcl result string
  13.  
  14.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.           ####iiiinnnncccclllluuuuddddeeee <<<<ttttccccllll....hhhh>>>>
  16.  
  17.           TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt(_i_n_t_e_r_p, _s_t_r_i_n_g, _f_r_e_e_P_r_o_c)
  18.  
  19.           TTTTccccllll____AAAAppppppppeeeennnnddddRRRReeeessssuuuulllltttt((((_i_n_t_e_r_p, _s_t_r_i_n_g, _s_t_r_i_n_g, ... , ((((cccchhhhaaaarrrr ****)))) NNNNUUUULLLLLLLL)
  20.  
  21.           TTTTccccllll____AAAAppppppppeeeennnnddddEEEElllleeeemmmmeeeennnntttt(_i_n_t_e_r_p, _s_t_r_i_n_g)                             |
  22.  
  23.           TTTTccccllll____RRRReeeesssseeeettttRRRReeeessssuuuulllltttt(_i_n_t_e_r_p)
  24.  
  25.           TTTTccccllll____FFFFrrrreeeeeeeeRRRReeeessssuuuulllltttt(_i_n_t_e_r_p)
  26.  
  27.      AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  28.           Tcl_Interp     *_i_n_t_e_r_p    (out)     Interpreter whose result
  29.                                               is to be modified.
  30.  
  31.           char           *_s_t_r_i_n_g    (in)      String value  to  become
  32.                                               result  for _i_n_t_e_r_p or to
  33.                                               be appended to  existing
  34.                                               result.
  35.  
  36.           Tcl_FreeProc   _f_r_e_e_P_r_o_c   (in)      Address of procedure  to
  37.                                               call  to release storage
  38.                                               at      _s_t_r_i_n_g,       or
  39.                                               TTTTCCCCLLLL____SSSSTTTTAAAATTTTIIIICCCC, TTTTCCCCLLLL____DDDDYYYYNNNNAAAAMMMMIIIICCCC,
  40.                                               or TTTTCCCCLLLL____VVVVOOOOLLLLAAAATTTTIIIILLLLEEEE.
  41.      _________________________________________________________________
  42.  
  43.  
  44.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  45.           The procedures described here are utilities for setting  the
  46.           result/error string in a Tcl interpreter.
  47.  
  48.           TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt arranges for _s_t_r_i_n_g to be  the  return  string
  49.           for  the  current  Tcl  command  in  _i_n_t_e_r_p,  replacing  any
  50.           existing result.  If _f_r_e_e_P_r_o_c is TTTTCCCCLLLL____SSSSTTTTAAAATTTTIIIICCCC  it  means  that
  51.           _s_t_r_i_n_g   refers  to  an  area  of  static  storage  that  is
  52.           guaranteed not to be modified until at least the  next  call
  53.           to  TTTTccccllll____EEEEvvvvaaaallll.   If  _f_r_e_e_P_r_o_c  is  TTTTCCCCLLLL____DDDDYYYYNNNNAAAAMMMMIIIICCCC  it means that
  54.           _s_t_r_i_n_g was allocated with a call to mmmmaaaalllllllloooocccc(((()))) and is now  the
  55.           property  of the Tcl system.  TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt will arrange for
  56.           the string's storage to be released by calling  ffffrrrreeeeeeee(((())))  when
  57.           it  is  no  longer  needed.   If _f_r_e_e_P_r_o_c is TTTTCCCCLLLL____VVVVOOOOLLLLAAAATTTTIIIILLLLEEEE it
  58.           means that _s_t_r_i_n_g points to an area of memory that is likely
  59.           to be overwritten when TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt returns (e.g. it points
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 7/10/95)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt((((3333))))            TTTTccccllll ((((7777....0000))))            TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt((((3333))))
  71.  
  72.  
  73.  
  74.           to something in a stack frame).  In this case  TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt
  75.           will  make  a  copy  of  the string in dynamically allocated
  76.           storage and arrange for the copy to be the return string for
  77.           the current Tcl command.
  78.  
  79.           If _f_r_e_e_P_r_o_c isn't one of the values TTTTCCCCLLLL____SSSSTTTTAAAATTTTIIIICCCC, TTTTCCCCLLLL____DDDDYYYYNNNNAAAAMMMMIIIICCCC,
  80.           and TTTTCCCCLLLL____VVVVOOOOLLLLAAAATTTTIIIILLLLEEEE, then it is the address of a procedure that
  81.           Tcl  should  call  to  free   the   string.    This   allows
  82.           applications  to  use non-standard storage allocators.  When
  83.           Tcl no longer needs the storage for the string, it will call
  84.           _f_r_e_e_P_r_o_c.   _F_r_e_e_P_r_o_c  should  have arguments and result that
  85.           match the type TTTTccccllll____FFFFrrrreeeeeeeePPPPrrrroooocccc:
  86.  
  87.                typedef void Tcl_FreeProc(char *_b_l_o_c_k_P_t_r);
  88.  
  89.           When _f_r_e_e_P_r_o_c is called, its _b_l_o_c_k_P_t_r will  be  set  to  the
  90.           value of _s_t_r_i_n_g passed to TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt.
  91.  
  92.           If  _s_t_r_i_n_g  is  NNNNUUUULLLLLLLL,   then   _f_r_e_e_P_r_o_c   is   ignored   and
  93.           TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt re-initializes _i_n_t_e_r_p's result to point to the
  94.           pre-allocated result area,  with  an  empty  string  in  the
  95.           result area.
  96.  
  97.           If TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt is called at a time  when  _i_n_t_e_r_p  holds  a
  98.           result,  TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt does whatever is necessary to dispose
  99.           of the old result  (see  the  TTTTccccllll____IIIInnnntttteeeerrrrpppp  manual  entry  for
  100.           details on this).
  101.  
  102.           TTTTccccllll____AAAAppppppppeeeennnnddddRRRReeeessssuuuulllltttt makes it easy to build up  Tcl  results  in
  103.           pieces.   It  takes each of its _s_t_r_i_n_g arguments and appends
  104.           them in order to the current result associated with  _i_n_t_e_r_p.
  105.           If  the  result  is  in  its initialized empty state (e.g. a
  106.           command procedure was just invoked  or  TTTTccccllll____RRRReeeesssseeeettttRRRReeeessssuuuulllltttt  was
  107.           just  called),  then TTTTccccllll____AAAAppppppppeeeennnnddddRRRReeeessssuuuulllltttt sets the result to the
  108.           concatenation of its _s_t_r_i_n_g arguments.  TTTTccccllll____AAAAppppppppeeeennnnddddRRRReeeessssuuuulllltttt may
  109.           be  called repeatedly as additional pieces of the result are
  110.           produced.  TTTTccccllll____AAAAppppppppeeeennnnddddRRRReeeessssuuuulllltttt takes care of  all  the  storage
  111.           management  issues associated with managing _i_n_t_e_r_p's result,
  112.           such as allocating a larger result area if  necessary.   Any
  113.           number  of  _s_t_r_i_n_g arguments may be passed in a single call;
  114.           the last argument in the list must be a NULL pointer.
  115.  
  116.           TTTTccccllll____AAAAppppppppeeeennnnddddEEEElllleeeemmmmeeeennnntttt is similar to TTTTccccllll____AAAAppppppppeeeennnnddddRRRReeeessssuuuulllltttt in that  it
  117.           allows   results   to  be  built  up  in  pieces.   However,
  118.           TTTTccccllll____AAAAppppppppeeeennnnddddEEEElllleeeemmmmeeeennnntttt takes only a single _s_t_r_i_n_g argument and it
  119.           appends  that argument to the current result as a proper Tcl
  120.           list element.  TTTTccccllll____AAAAppppppppeeeennnnddddEEEElllleeeemmmmeeeennnntttt adds backslashes or  braces
  121.           if necessary to ensure that _i_n_t_e_r_p's result can be parsed as
  122.           a list and  that  _s_t_r_i_n_g  will  be  extracted  as  a  single
  123.           element.   Under  normal  conditions, TTTTccccllll____AAAAppppppppeeeennnnddddEEEElllleeeemmmmeeeennnntttt will
  124.           add a space character to _i_n_t_e_r_p's result just before  adding
  125.           the  new  list  element,  so  that  the list elements in the
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 7/10/95)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt((((3333))))            TTTTccccllll ((((7777....0000))))            TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt((((3333))))
  137.  
  138.  
  139.  
  140.           result are properly separated.   However  if  the  new  list  |
  141.           element  is  the  first in a list or sub-list (i.e. _i_n_t_e_r_p's  |
  142.           current result is empty, or consists of the single character  |
  143.           ``{'',  or  ends  in the characters `` {'') then no space is  |
  144.           added.
  145.  
  146.           TTTTccccllll____RRRReeeesssseeeettttRRRReeeessssuuuulllltttt clears the result for  _i_n_t_e_r_p,  freeing  the
  147.           memory   associated  with  it  if  the  current  result  was
  148.           dynamically allocated.  It leaves the result in  its  normal
  149.           initialized  state  with _i_n_t_e_r_p->_r_e_s_u_l_t pointing to a static
  150.           buffer containing TTTTCCCCLLLL____RRRREEEESSSSUUUULLLLTTTT____SSSSIIIIZZZZEEEE characters, of  which  the
  151.           first  character  is  zero.  TTTTccccllll____RRRReeeesssseeeettttRRRReeeessssuuuulllltttt also clears the
  152.           error    state    managed    by     TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo     and
  153.           TTTTccccllll____SSSSeeeettttEEEErrrrrrrroooorrrrCCCCooooddddeeee.
  154.  
  155.           TTTTccccllll____FFFFrrrreeeeeeeeRRRReeeessssuuuulllltttt is a macro that performs part of the work  of
  156.           TTTTccccllll____RRRReeeesssseeeettttRRRReeeessssuuuulllltttt.   It  frees  up  the memory associated with
  157.           _i_n_t_e_r_p's result and sets _i_n_t_e_r_p->_f_r_e_e_P_r_o_c to  zero,  but  it
  158.           doesn't   change   _i_n_t_e_r_p->_r_e_s_u_l_t   or  clear  error  state.
  159.           TTTTccccllll____FFFFrrrreeeeeeeeRRRReeeessssuuuulllltttt is most commonly used  when  a  procedure  is
  160.           about to replace one result value with another.
  161.  
  162.  
  163.      SSSSEEEEEEEE AAAALLLLSSSSOOOO
  164.           Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp
  165.  
  166.  
  167.      KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  168.           append,  command,  element,  list,  result,  return   value,
  169.           interpreter
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 7/10/95)
  196.  
  197.  
  198.  
  199.